Skip Headers

Oracle® Database PL/SQL Packages and Types Reference 10g Release 2 (10.2) Part Number B14258-01 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next

# 177 UTL_SMTP

The `UTL_SMTP` package is designed for sending electronic mails (emails) over Simple Mail Transfer Protocol (SMTP) as specified by RFC821.

See Also: How to use the SMTP package to send email in Oracle Database Application Developer's Guide - Fundamentals

This chapter contains the following topics:

- Using UTL_SMTP

  - Overview

  - Types

  - Reply Codes

  - Exceptions

  - Rules and Limits

  - Examples

- Summary of UTL_SMTP Subprograms

## Using UTL_SMTP

- Overview

- Types

- Reply Codes

- Exceptions

- Rules and Limits

- Examples

### Overview

The protocol consists of a set of commands for an email client to dispatch emails to a SMTP server. The `UTL_SMTP` package provides interfaces to the SMTP commands. For many of the commands, the package provides both a procedural and a functional interface. The functional form returns the reply from the server for processing by the client. The procedural form checks the reply and will raise an exception if the reply indicates a transient (400-range reply code) or permanent error (500-range reply code). Otherwise, it discards the reply.

Note that the original SMTP protocol communicates using 7-bit ASCII. Using `UTL_SMTP`, all text data (in other words, those in VARCHAR2) will be converted to US7ASCII before it is sent over the wire to the server. Some implementations of SMTP servers that support SMTP extension 8BITMIME [RFC1652] support full 8-bit communication between client and server. The body of the DATA command may be transferred in full 8 bits, but the rest of the SMTP command and response should be in 7 bits. When the target SMTP server supports 8BITMIME extension, users of multibyte databases may convert their non-US7ASCII, multibyte VARCHAR2 data to RAW and use the WRITE_RAW_DATA subprogram to send multibyte data using 8-bit MIME encoding.

`UTL_SMTP` provides for SMTP communication as specified in RFC821, but does not provide an API to format the content of the message according to RFC 822 (for example, setting the subject of an electronic mail).You must format the message appropriately. In addition, `UTL_SMTP` does not have the functionality to implement an SMTP server for an email clients to send emails using SMTP.

Note : RFC documents are "Request for Comments" documents that describe proposed standards for public review on the Internet. For the actual RFC documents, please refer to: `http://www.ietf.org/rfc/`

### Types

- CONNECTION Record Type

- REPLY, REPLIES Record Types

#### CONNECTION Record Type

This is a PL/SQL record type used to represent an SMTP connection.

Syntax

    TYPE connection IS RECORD (
        host              VARCHAR2(255),      -- remote host name
        port              PLS_INTEGER,        -- remote port number
        tx_timeout        PLS_INTEGER,        -- Transfer time out (in seconds)
        private_tcp_con   utl_tcp.connection, -- private, for implementation use
        private_state     PLS_INTEGER         -- private, for implementation use
    );

Fields

Table 177-1 CONNECTION Record Type Fields

Field | Description
--- | ---
`host` | The name of the remote host when connection is established. `NULL` when no connection is established.
`port` | The port number of the remote SMTP server connected. `NULL` when no connection is established.
`tx_timeout` | The time in seconds that the `UTL_SMTP` package waits before giving up in a read or write operation in this connection. In read operations, this package gives up if no data is available for reading immediately. In write operations, this package gives up if the output buffer is full and no data is to be sent into the network without being blocked. `0` indicates not to wait at all. `NULL` indicates to wait forever.
`private_tcp_con` | Private, for implementation use only. You should not modify this field.
`private_state` | Private, for implementation use only. You should not modify this field.

Usage Notes

The read-only fields in a connection record are used to return information about the SMTP connection after the connection is successfully made with `open_connection()`. Changing the values of these fields has no effect on the connection. The fields `private_xxx` are for implementation use only. You should not modify these fields.

#### REPLY, REPLIES Record Types

These are PL/SQL record types used to represent an SMTP reply line. Each SMTP reply line consists of a reply code followed by a text message. While a single reply line is expected for most SMTP commands, some SMTP commands expect multiple reply lines. For those situations, a PL/SQL table of reply records is used to represent multiple reply lines.

Syntax

    TYPE reply IS RECORD (
      code    PLS_INTEGER,       -- 3-digit reply code
      text    VARCHAR2(508)      -- text message
    );
    TYPE replies IS TABLE OF reply INDEX BY BINARY_INTEGER;   -- multiple reply lines

Fields

Table 177-2 REPLY, REPLIES Record Type Fields

Field | Description
--- | ---
`code` | The 3-digit reply code.
`text` | The text message of the reply.

### Reply Codes

The following is a list of the SMTP reply codes.

Table 177-3 SMTP Reply Codes

Reply Code | Meaning
--- | ---
`211` | System status, or system help reply
`214` | Help message [Information on how to use the receiver or the meaning of a particular non-standard command; this reply is useful only to the human user]
`220` | <domain> Service ready
`221` | <domain> Service closing transmission channel
`250` | Requested mail action okay, completed
`251` | User not local; will forward to <forward-path>
`252` | OK, pending messages for node `<node>` started. Cannot `VRFY` user (for example, info is not local), but will take message for this user and attempt delivery.
`253` | OK, <messages> pending messages for node `<node>` started
`354` | Start mail input; end with `<CRLF>.<CRLF>`
`355` | Octet-offset is the transaction offset
`421` | <domain> Service not available, closing transmission channel (This may be a reply to any command if the service knows it must shut down.)
`450` | Requested mail action not taken: mailbox unavailable [for example, mailbox busy]
`451` | Requested action terminated: local error in processing
`452` | Requested action not taken: insufficient system storage
`453` | You have no mail.
`454` | TLS not available due to temporary reason. Encryption required for requested authentication mechanism.
`458` | Unable to queue messages for node `<node>`
`459` | Node `<node>` not allowed: `reason`
`500` | Syntax error, command unrecognized (This may include errors such as command line too long.)
`501` | Syntax error in parameters or arguments
`502` | Command not implemented
`503` | Bad sequence of commands
`504` | Command parameter not implemented
`521` | `<Machine>` does not accept mail.
`530` | Must issue a `STARTTLS` command first. Encryption required for requested authentication mechanism.
`534` | Authentication mechanism is too weak.
`538` | Encryption required for requested authentication mechanism.
`550` | Requested action not taken: mailbox unavailable [for , mailbox not found, no access]
`551` | User not local; please try <forward-path>
`552` | Requested mail action terminated: exceeded storage allocation
`553` | Requested action not taken: mailbox name not allowed [for example, mailbox syntax incorrect]
`554` | Transaction failed

### Exceptions

The table lists the exceptions that can be raised by the interface of the `UTL_SMTP` package. The network error is transferred to a reply code of 421- service not available.

Table 177-4 UTL_SMTP Exceptions

`INVALID_OPERATION` | Raised when an invalid operation is made. In other words, calling API other than `write_data(), write_raw_data()` or `close_data()` after open_data() is called, or calling `write_data(), write_raw_data()` or `close_data()` without first calling `open_data().`
`TRANSIENT_ERROR` | Raised when receiving a reply code in 400 range.
`PERMANENT_ERROR` | Raised when receiving a reply code in 500 range.

### Rules and Limits

No limitation or range-checking is imposed by the API. However, you should be aware of the following size limitations on various elements of SMTP. Sending data that exceed these limits may result in errors returned by the server.

Table 177-5 SMTP Size Limitation

Element | Size Limitation
--- | ---
`user` | The maximum total length of a user name is 64 characters.
`domain` | The maximum total length of a domain name or number is 64 characters.
`path` | The maximum total length of a reverse-path or forward-path is 256 characters (including the punctuation and element separators).
`command line` | The maximum total length of a command line including the command word and the `<CRLF>` is 512 characters.
`reply line` | The maximum total length of a reply line including the reply code and the `<CRLF>` is 512 characters.
`text line` | The maximum total length of a text line including the `<CRLF>` is 1000 characters (but not counting the leading dot duplicated for transparency).
`recipients buffer` | The maximum total number of recipients that must be buffered is 100 recipients.

### Examples

The following example illustrates how `UTL_SMTP` is used by an application to send e-mail. The application connects to an SMTP server at port 25 and sends a simple text message.

    DECLARE
      c UTL_SMTP.CONNECTION;

      PROCEDURE send_header(name IN VARCHAR2, header IN VARCHAR2) AS
      BEGIN
        UTL_SMTP.WRITE_DATA(c, name || ': ' || header || UTL_TCP.CRLF);
      END;

    BEGIN
      c := UTL_SMTP.OPEN_CONNECTION('smtp-server.acme.com');
      UTL_SMTP.HELO(c, 'foo.com');
      UTL_SMTP.MAIL(c, 'sender@foo.com');
      UTL_SMTP.RCPT(c, 'recipient@foo.com');
      UTL_SMTP.OPEN_DATA(c);
      send_header('From',    '"Sender" <sender@foo.com>');
      send_header('To',      '"Recipient" <recipient@foo.com>');
      send_header('Subject', 'Hello');
      UTL_SMTP.WRITE_DATA(c, UTL_TCP.CRLF || 'Hello, world!');
      UTL_SMTP.CLOSE_DATA(c);
      UTL_SMTP.QUIT(c);
    EXCEPTION
      WHEN utl_smtp.transient_error OR utl_smtp.permanent_error THEN
        BEGIN
          UTL_SMTP.QUIT(c);
        EXCEPTION
          WHEN UTL_SMTP.TRANSIENT_ERROR OR UTL_SMTP.PERMANENT_ERROR THEN
            NULL; -- When the SMTP server is down or unavailable, we don't have
                  -- a connection to the server. The QUIT call will raise an
                  -- exception that we can ignore.
        END;
        raise_application_error(-20000,
          'Failed to send mail due to the following error: ' || sqlerrm);
    END;

## Summary of UTL_SMTP Subprograms

Table 177-6 UTL_SMTP Package Subprograms

Subprogram | Description
--- | ---
CLOSE_DATA Function and Procedure | Closes the data session
COMMAND Function and Procedure | Performs a generic SMTP command
COMMAND_REPLIES Function | Performs initial handshaking with SMTP server after connecting
DATA Function and Procedure | Performs initial handshaking with SMTP server after connecting, with extended information returned
EHLO Function and Procedure | Performs initial handshaking with SMTP server after connecting, with extended information returned
HELO Function and Procedure | Performs initial handshaking with SMTP server after connecting
HELP Function | Sends `HELP` command
MAIL Function and Procedure | Initiates a mail transaction with the server, the destination is a mailbox
NOOP Function and Procedure | The null command
OPEN_CONNECTION Functions | Opens a connection to an SMTP server
OPEN_DATA Function and Procedure | S`ends the DATA` command
QUIT Function and Procedure | Terminates an SMTP session and disconnects from the server
RCPT Function | Specifies the recipient of an e-mail message
RSET Function and Procedure | Terminates the current mail transaction
VRFY Function | Verifies the validity of a destination e-mail address
WRITE_DATA Procedure | Writes a portion of the e-mail message
WRITE_RAW_DATA Procedure | Writes a portion of the e-mail message with `RAW` data

### CLOSE_DATA Function and Procedure

The `CLOSE_DATA` call ends the e-mail message by sending the sequence `<CR><LF>.<CR><LF>` (a single period at the beginning of a line).

Syntax

    UTL_SMTP.CLOSE_DATA (
       c     IN OUT NOCOPY connection)
    RETURN reply;

    UTL_SMTP.CLOSE_DATA (
       c     IN OUT NOCOPY connection);

Parameters

Table 177-7 CLOSE_DATA Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.

Return Values

Table 177-8 CLOSE_DATA Function and Procedure Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

The calls to `OPEN_DATA`, `WRITE_DATA`, `WRITE_RAW_DATA` and `CLOSE_DATA` must be made in the right order. A program calls `OPEN_DATA` to send the `DATA` command to the SMTP server. After that, it can call `WRITE_DATA` or `WRITE_RAW_DATA` repeatedly to send the actual data. The data is terminated by calling `CLOSE_DATA`. After `OPEN_DATA` is called, the only subprograms that can be called are `WRITE_DATA`, `WRITE_RAW_DATA,` or `CLOSE_DATA`. A call to other APIs will result in an `INVALID_OPERATION` exception being raised.

`CLOSE_DATA` should be called only after `OPEN_CONNECTION`, `HELO` or `EHLO`, `MAIL`, and `RCPT` have been called. The connection to the SMTP server must be open and a mail transaction must be active when this routine is called.

Note that there is no function form of `WRITE_DATA` because the SMTP server does not respond until the data-terminator is sent during the call to `CLOSE_DATA`.

### COMMAND Function and Procedure

This function/procedure performs a generic SMTP command.

Syntax

    UTL_SMTP.COMMAND (
       c     IN OUT NOCOPY    connection,
       cmd   IN               VARCHAR2,
       arg   IN               VARCHAR2 DEFAULT NULL)
    RETURN reply;

    UTL_SMTP.COMMAND (
       c     IN OUT NOCOPY    connection,
       cmd   IN               VARCHAR2,
       arg   IN               VARCHAR2 DEFAULT NULL);

Parameters

Table 177-9 COMMAND Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`cmd` | The SMTP command to send to the server.
`arg` | The optional argument to the SMTP argument. A space will be inserted between `cmd` and `arg`.

Return Values

Table 177-10 COMMAND Function and Procedure Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

This function is used to invoke generic SMTP commands. Use `COMMAND` if only a single reply line is expected. Use `COMMAND_REPLIES` if multiple reply lines are expected.

For `COMMAND`, if multiple reply lines are returned from the SMTP server, it returns the last reply line only.

### COMMAND_REPLIES Function

This functions performs a generic SMTP command.

Syntax

    UTL_SMTP.COMMAND_REPLIES (
       c     IN OUT NOCOPY    connection,
       cmd   IN               VARCHAR2,
       arg   IN               VARCHAR2 DEFAULT NULL)
    RETURN replies;

Parameters

Table 177-11 COMMAND_REPLIES Function Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`cmd` | The SMTP command to send to the server.
`arg` | The optional argument to the SMTP argument. A space will be inserted between `cmd` and `arg`.

Return Values

Table 177-12 COMMAND_REPLIES Function Return Values

Return Value | Description
--- | ---
`replies` | Reply of the command (see REPLY, REPLIES Record Types).

Usage Notes

This function is used to invoke generic SMTP commands. Use `COMMAND` if only a single reply line is expected. Use `COMMAND_REPLIES` if multiple reply lines are expected.

For `COMMAND`, if multiple reply lines are returned from the SMTP server, it returns the last reply line only.

### DATA Function and Procedure

This function/procedure specifies the body of an e-mail message.

Syntax

    UTL_SMTP.DATA (
       c     IN OUT NOCOPY connection
       body  IN  VARCHAR2 CHARACTER SET ANY_CS)
    RETURN reply;

    UTL_SMTP.DATA (
       c     IN OUT NOCOPY connection
       body  IN VARCHAR2 CHARACTER SET ANY_CS);

Parameters

Table 177-13 DATA Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP Connection.
`body` | The text of the message to be sent, including headers, in [RFC822] format.

Return Values

Table 177-14 DATA Function and Procedure Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

The application must ensure that the contents of the body parameter conform to the MIME(RFC822) specification. The `DATA` routine will terminate the message with a `<CR><LF>.<CR><LF>` sequence (a single period at the beginning of a line), as required by RFC821. It will also translate any sequence of `<CR><LF>.<CR><LF>` (single period) in body to `<CR><LF>..<CR><LF>` (double period). This conversion provides the transparency as described in Section 4.5.2 of RFC821.

The `DATA` call should be called only after `OPEN_CONNECTION`, `HELO` or `EHLO`, `MAIL` and `RCPT` have been called. The connection to the SMTP server must be open, and a mail transaction must be active when this routine is called.

The expected response from the server is a message beginning with status code 250. The 354 response received from the initial `DATA` command will not be returned to the caller.

### EHLO Function and Procedure

This function/procedure performs initial handshaking with SMTP server after connecting, with extended information returned.

Syntax

    UTL_SMTP.EHLO (
       c       IN OUT NOCOPY connection,
       domain  IN)
    RETURN replies;

    UTL_SMTP.EHLO (
       c       IN OUT NOCOPY connection,
       domain  IN);

Parameters

Table 177-15 EHLO Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`domain` | The domain name of the local (sending) host. Used for identification purposes.

Return Values

Table 177-16 EHLO Function and Procedure Return Values

Return Value | Description
--- | ---
`replies` | Reply of the command (see REPLY, REPLIES Record Types).

Usage Notes

The `EHLO` interface is identical to `HELO` except that it allows the server to return more descriptive information about its configuration. [RFC1869] specifies the format of the information returned, which the PL/SQL application can retrieve using the functional form of this call. For compatibility with `HELO,` each line of text returned by the server begins with status code 250.

Related Functions

`HELO`

### HELO Function and Procedure

This function/procedure performs initial handshaking with SMTP server after connecting.

Syntax

    UTL_SMTP.HELO (
       c       IN OUT NOCOPY   connection,
       domain  IN              VARCHAR2)
    RETURN reply;

    UTL_SMTP.HELO (
       c       IN OUT NOCOPY   connection,
       domain  IN              VARCHAR2);

Parameters

Table 177-17 HELO Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`domain` | The domain name of the local (sending) host. Used for identification purposes.

Return Values

Table 177-18 HELO Function and Procedure Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

RFC 821 specifies that the client must identify itself to the server after connecting. This routine performs that identification. The connection must have been opened through a call to OPEN_CONNECTION Functions before calling this routine.

The expected response from the server is a message beginning with status code 250.

Related Functions

`EHLO`

### HELP Function

This function sends the `HELP` command.

Syntax

    UTL_SMTP.HELP (
       c         IN OUT NOCOPY   connection,
       command   IN              VARCHAR2 DEFAULT NULL)
    RETURN replies;

Parameters

Table 177-19 HELP Function Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`command` | The command to get the help message.

Return Values

Table 177-20 HELP Function Return Values

Return Value | Description
--- | ---
`replies` | Reply of the command (see REPLY, REPLIES Record Types).

### MAIL Function and Procedure

This function/procedure initiates a mail transaction with the server. The destination is a mailbox.

Syntax

    UTL_SMTP.MAIL (
       c           IN OUT NOCOPY   connection,
       sender      IN              VARCHAR2,
       parameters  IN              VARCHAR2 DEFAULT NULL)
    RETURN reply;

    UTL_SMTP.MAIL (
       c           IN OUT NOCOPY   connection,
       sender      IN              VARCHAR2,
       parameters  IN              VARCHAR2 DEFAULT NULL);

Parameters

Table 177-21 MAIL Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`sender` | The e-mail address of the user sending the message.
`parameters` | The additional parameters to MAIL command as defined in Section 6 of [RFC1869]. It should follow the format of "XXX=XXX (XXX=XXX ....)".

Return Values

Table 177-22 MAIL Function and Procedure Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

This command does not send the message; it simply begins its preparation. It must be followed by calls to `RCPT` and `DATA` to complete the transaction. The connection to the SMTP server must be open and a `HELO` or `EHLO` command must have already been sent.

The expected response from the server is a message beginning with status code 250.

### NOOP Function and Procedure

The null command.

Syntax

    UTL_SMTP.NOOP (
       c  IN OUT NOCOPY connection)
    RETURN reply;

    UTL_SMTP.NOOP (
       c  IN OUT NOCOPY connection);

Parameter

Table 177-23 NOOP Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.

Return Values

Table 177-24 NOOP Function and Procedure Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

This command has no effect except to elicit a successful reply from the server. It can be issued at any time after the connection to the server has been established with `OPEN_CONNECTION`. The `NOOP` command can be used to verify that the server is still connected and is listening properly.

This command will always reply with a single line beginning with status code 250.

### OPEN_CONNECTION Functions

These functions open a connection to an SMTP server.

Syntax

    UTL_SMTP.OPEN_CONNECTION (
       host        IN  VARCHAR2,
       port        IN  PLS_INTEGER DEFAULT 25,
       c           OUT connection,
       tx_timeout  IN  PLS_INTEGER DEFAULT NULL)
    RETURN reply;

    UTL_SMTP.OPEN_CONNECTION (
       host        IN  VARCHAR2,
       port        IN  PLS_INTEGER DEFAULT 25,
       tx_timeout  IN  PLS_INTEGER DEFAULT NULL)
    RETURN connection;

Parameters

Table 177-25 OPEN_CONNECTION Functions Parameters

Parameter | Description
--- | ---
`host` | The name of the SMTP server host
`port` | The port number on which SMTP server is listening (usually 25).
`c` | The SMTP connection.
`tx_timeout` | The time in seconds that the `UTL_SMTP` package waits before giving up in a read or write operation in this connection. In read operations, this package gives up if no data is available for reading immediately. In write operations, this package gives up if the output buffer is full and no data is to be sent into the network without being blocked. `0` indicates not to wait at all. `NULL` indicates to wait forever.

Return Values

Table 177-26 OPEN_CONNECTION Functions Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

- The expected response from the server is a message beginning with status code 220.

- The version of `OPEN_CONNECTION` that returns `UTL_SMTP`.`CONNECTION` record checks the reply code returned by an SMTP server when the connection is first established. It raises an exception when the reply indicates an error. Otherwise, it discards the reply. If a user is interested in examining the reply, he or she can invoke the version of `OPEN_CONNECTION` that returns `REPLY`.

- A timeout on the `WRITE` operations feature is not supported in the current release of this package.

### OPEN_DATA Function and Procedure

`OPEN_DATA` sends the `DATA` command after which you can use `WRITE_DATA` and `WRITE_RAW_DATA` to write a portion of the e-mail message.

Syntax

    UTL_SMTP.OPEN_DATA (
       c     IN OUT NOCOPY connection)
    RETURN reply;

    UTL_SMTP.OPEN_DATA (
       c     IN OUT NOCOPY connection);

Parameters

Table 177-27 OPEN_DATA Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`data` | The portion of the text of the message to be sent, including headers, in [RFC822] format.

Return Values

Table 177-28 OPEN_DATA Function and Procedure Function Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

The calls to `OPEN_DATA`, `WRITE_DATA`, `WRITE_RAW_DATA` and `CLOSE_DATA` must be made in the right order. A program calls `OPEN_DATA` to send the `DATA` command to the SMTP server. After that, it can call `WRITE_DATA` or `WRITE_RAW_DATA` repeatedly to send the actual data. The data is terminated by calling `CLOSE_DATA`. After `OPEN_DATA` is called, the only subprograms that can be called are `WRITE_DATA`, `WRITE_RAW_DATA,` or `CLOSE_DATA`. A call to other APIs will result in an `INVALID_OPERATION` exception being raised.

`OPEN_DATA` should be called only after `OPEN_CONNECTION`, `HELO` or `EHLO`, `MAIL`, and `RCPT` have been called. The connection to the SMTP server must be open and a mail transaction must be active when this routine is called.

### QUIT Function and Procedure

This function terminates an SMTP session and disconnects from the server.

Syntax

    UTL_SMTP.QUIT (
       c  IN OUT NOCOPY connection)
    RETURN reply;

    UTL_SMTP.QUIT (
       c  IN OUT NOCOPY connection);

Parameter

Table 177-29 QUIT Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.

Return Values

Table 177-30 QUIT Function and Procedure Function Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

The `QUIT` command informs the SMTP server of the client's intent to terminate the session. It then closes the connection established by `OPEN_CONNECTION` which must have been called before executing this command. If a mail transaction is in progress when `QUIT` is issued, it is abandoned in the same manner as `RSET.`

The function form of this command returns a single line beginning with the status code 221 on successful termination. In all cases, the connection to the SMTP server is closed. The fields `REMOTE_HOST` and `REMOTE_PORT` of `c` are reset.

Related Functions

`RSET`

### RCPT Function

This function/procedure specifies the recipient of an e-mail message.

Syntax

    UTL_SMTP.RCPT (
       c           IN OUT NOCOPY     connection,
       recipient   IN                VARCHAR2,
       parameters  IN                VARCHAR2 DEFAULT NULL)
    RETURN reply;

    UTL_SMTP.RCPT (
       c           IN OUT NOCOPY     connection,
       recipient   IN                VARCHAR2,
       parameters  IN                VARCHAR2 DEFAULT NULL);

Table 177-31 RCPT Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`recipient` | The e-mail address of the user to which the message is being sent.
`parameters` | The additional parameters to RCPT command as defined in Section 6 of [RFC1869]. It should follow the format of "XXX=XXX (XXX=XXX ....)".

Return Values

Table 177-32 RCPT Function and Procedure Function Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

To send a message to multiple recipients, call this routine multiple times. Each invocation schedules delivery to a single e-mail address. The message transaction must have been begun by a prior call to `MAIL`, and the connection to the mail server must have been opened and initialized by prior calls to `OPEN_CONNECTION` and `HELO` or `EHLO` respectively.

The expected response from the server is a message beginning with status code 250 or 251.

### RSET Function and Procedure

This function terminates the current mail transaction.

Syntax

    UTL_SMTP.RSET (
       c  IN OUT NOCOPY connection)
    RETURN reply;

    UTL_SMTP.RSET (
       c  IN OUT NOCOPY connection);

Parameters

Table 177-33 RSET Function and Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.

Return Values

Table 177-34 RSET Function and Procedure Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

This command allows the client to abandon a mail message it was in the process of composing. No mail will be sent. The client can call `RSET` at any time after the connection to the SMTP server has been opened by means of `OPEN_CONNECTION` until `DATA` or `OPEN_DATA` is called. Once the email data has been sent, it will be too late to prevent the email from being sent.

The server will always respond to `RSET` with a message beginning with status code 250.

Related Functions

`QUIT`

### VRFY Function

This function verifies the validity of a destination e-mail address.

Syntax

    UTL_SMTP.VRFY (
       c          IN OUT NOCOPY connection
       recipient  IN VARCHAR2)
    RETURN reply;

Parameters

Table 177-35 VRFY Function Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`recipient` | The e-mail address to be verified.

Return Values

Table 177-36 VRFY Function Return Values

Return Value | Description
--- | ---
`reply` | Reply of the command (see REPLY, REPLIES Record Types). In cases where there are multiple replies, the last reply will be returned.

Usage Notes

The server attempts to resolve the destination address `recipient.` If successful, it returns the recipient's full name and fully qualified mailbox path. The connection to the server must have already been established by means of `OPEN_CONNECTION` and `HELO` or `EHLO` before making this request.

Successful verification returns one or more lines beginning with status code 250 or 251.

### WRITE_DATA Procedure

`U`se `WRITE_DATA` to write a portion of the e-mail message. A repeat call to `WRITE_DATA` appends data to the e-mail message.

Syntax

    UTL_SMTP.WRITE_DATA (
       c     IN OUT NOCOPY connection,
       data  IN VARCHAR2 CHARACTER SET ANY_CS);

Parameters

Table 177-37 WRITE_DATA Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`data` | The portion of the text of the message to be sent, including headers, in [RFC822] format.

Usage Notes

The calls to `OPEN_DATA`, `WRITE_DATA`, `WRITE_RAW_DATA` and `CLOSE_DATA` must be made in the right order. A program calls `OPEN_DATA` to send the `DATA` command to the SMTP server. After that, it can call `WRITE_DATA` or `WRITE_RAW_DATA` repeatedly to send the actual data. The data is terminated by calling `CLOSE_DATA`. After `OPEN_DATA` is called, the only subprograms that can be called are `WRITE_DATA`, `WRITE_RAW_DATA,` or `CLOSE_DATA`. A call to other APIs will result in an `INVALID_OPERATION` exception being raised.

The application must ensure that the contents of the body parameter conform to the MIME(RFC822) specification. The `DATA` routine will terminate the message with a `<CR><LF>.<CR><LF>` sequence (a single period at the beginning of a line), as required by RFC821. It will also translate any sequence of `<CR><LF>.<CR><LF>` (single period) in the body to `<CR><LF>..<CR><LF>` (double period). This conversion provides the transparency as described in Section 4.5.2 of RFC821.

Notice that this conversion is not bullet-proof. Consider this code fragment:

    UTL_SMTP.WRITE_DATA('some message.' || chr(13) || chr(10));
      UTL_SMTP.WRITE_DATA('.' || chr(13) || chr(10));

Since the sequence `<CR><LF>.<CR><LF>` is split between two calls to `WRITE_DATA`, the implementation of `WRITE_DATA` will not detect the presence of the data-terminator sequence, and therefore, will not perform the translation. It will be the responsibility of the user to handle such a situation, or it may result in premature termination of the message data.

`WRITE_DATA` should be called only after `OPEN_CONNECTION`, `HELO` or `EHLO`, `MAIL`, and `RCPT` have been called. The connection to the SMTP server must be open and a mail transaction must be active when this routine is called.

Note that there is no function form of `WRITE_DATA` because the SMTP server does not respond until the data-terminator is sent during the call to `CLOSE_DATA`.

Text (`VARCHAR2`) data sent using `WRITE_DATA` is converted to US7ASCII before it is sent. If the text contains multibyte characters, each multibyte character in the text that cannot be converted to US7ASCII is replaced by a '?' character. If 8BITMIME extension is negotiated with the SMTP server using the `EHLO` subprogram, multibyte `VARCHAR2` data can be sent by first converting the text to `RAW` using the `UTL_RAW` package, and then sending the `RAW` data using `WRITE_RAW_DATA`.

### WRITE_RAW_DATA Procedure

Use `WRITE_RAW_DATA` to write a portion of the e-mail message. A repeat call to `WRITE_RAW_DATA` appends data to the e-mail message.

Syntax

    UTL_SMTP.WRITE_RAW_DATA (
       c     IN OUT NOCOPY connection
       data  IN RAW);

Parameters

Table 177-38 WRITE_RAW_DATA Procedure Parameters

Parameter | Description
--- | ---
`c` | The SMTP connection.
`data` | The portion of the text of the message to be sent, including headers, in [RFC822] format.

Usage Notes

The calls to `OPEN_DATA`, `WRITE_DATA`, `WRITE_RAW_DATA` and `CLOSE_DATA` must be made in the right order. A program calls `OPEN_DATA` to send the `DATA` command to the SMTP server. After that, it can call `WRITE_DATA` or `WRITE_RAW_DATA` repeatedly to send the actual data. The data is terminated by calling `CLOSE_DATA`. After `OPEN_DATA` is called, the only subprograms that can be called are `WRITE_DATA`, `WRITE_RAW_DATA,` or `CLOSE_DATA`. A call to other APIs will result in an `INVALID_OPERATION` exception being raised.

The application must ensure that the contents of the body parameter conform to the MIME(RFC822) specification. The `DATA` routine will terminate the message with a `<CR><LF>.<CR><LF>` sequence (a single period at the beginning of a line), as required by RFC821. It will also translate any sequence of `<CR><LF>.<CR><LF>` (single period) in the body to `<CR><LF>..<CR><LF>` (double period). This conversion provides the transparency as described in Section 4.5.2 of RFC821.

Notice that this conversion is not bullet-proof. Consider this code fragment:

    UTL_SMTP.WRITE_DATA('some message.' || chr(13) || chr(10));
      UTL_SMTP.WRITE_DATA('.' || chr(13) || chr(10));

Since the sequence `<CR><LF>.<CR><LF>` is split between two calls to `WRITE_DATA`, the implementation of `WRITE_DATA` will not detect the presence of the data-terminator sequence, and therefore, will not perform the translation. It will be the responsibility of the user to handle such a situation, or it may result in premature termination of the message data.

`XXX_DATA` should be called only after `OPEN_CONNECTION`, `HELO` or `EHLO`, `MAIL`, and `RCPT` have been called. The connection to the SMTP server must be open and a mail transaction must be active when this routine is called.

Note that there is no function form of `WRITE_DATA` because the SMTP server does not respond until the data-terminator is sent during the call to `CLOSE_DATA`.

Text (`VARCHAR2`) data sent using `WRITE_DATA` is converted to US7ASCII before it is sent. If the text contains multibyte characters, each multibyte character in the text that cannot be converted to US7ASCII is replaced by a '?' character. If 8BITMIME extension is negotiated with the SMTP server using the `EHLO` subprogram, multibyte `VARCHAR2` data can be sent by first converting the text to `RAW` using the `UTL_RAW` package, and then sending the `RAW` data using `WRITE_RAW_DATA`.